package org.javanum.number;

/**
 * <p>Defines common operations for the Complex Field</p>
 * 
 * <p>This interface defines the <i>Polar Form</i> of the Complex Field.
 * Thus, elements which implement this interface are of the form 
 * {@code re^(it)}, where {@code r} and {@code t} are real numbers and 
 * {@code i = Math.sqrt(-1)}. {@code r} is usually called the 
 * <i>magnitude</i>, and {@code t} is typically called the 
 * <i>direction</i> or <i>angle</i>.</p>
 * 
 * <p>The complex field is also defined in Cartesian coordinates. For more 
 * information, see {@link CartesianComplexField}.</p>
 * 
 * @author Scott Fines 
 * Date: Oct 31, 2009
 *
 * @param <R> the return type of the Real subfield in this implementation
 * @param <V> the return type of this implementation
 * @param <T> the type of the backing data structure.
 */
public interface PolarComplexField<R extends RealField<R,T>,
									V extends PolarComplexField<R,V,T>,
									T extends Number> extends ComplexField<R,V,T>{
	/**
	 * @return the magnitude of {@code this}. Since numbers in this 
	 * implementation are represented as {@code re^(it)}, this method 
	 * returns {@code r}.
	 */
	public R magnitude();
	
	/**
	 * @return the angle of {@code this}. Since numbers in this 
	 * implementation are represented as {@code re^(it)}, this method 
	 * returns {@code t}.
	 */
	public R angle();
	
	/**
	 * <p>The <i>complex conjugate</i> of {@code z=re^(it)} is the number 
	 * {@code w = re^(-it)}</p>
	 * @return the complex conjugate of {@code this}.
	 */
	public V conjugate();
	
	/**
	 * <p>The <i>modulus</i> of a complex number is defined as the distance 
	 * from the origin to that number. In the case of the polar form, 
	 * if the complex number is {@code re^(it)}, then the modulus of that
	 * number is defined as {@code r}.</p>
	 *  
	 * @return the modulus of {@code this}.
	 */
	public T modulus();
	
	/**
	 * 
	 * @param <K> the return type as an implementation of the 
	 * {@link CartesianComplexField}.
	 * @return {@code this} in cartesian form--that is, as an 
	 * implementation of {@link CartesianComplexField}.
	 */
	public <K extends CartesianComplexField<R, K, T>> K cartesianForm();

}
